Add PEP 484 type hints to transpiler analysis and utility passes by Hadar01 · Pull Request #15832 · Qiskit/qiskit

Hadar01 · 2026-03-18T22:22:46Z

What this PR does

Adds PEP 484 type annotations and improves docstrings across 12 transpiler
analysis and utility passes:

Analysis passes (qiskit/transpiler/passes/analysis/):
CountOps, Depth, Size, Width, NumQubits, NumTensorFactors,
CountOpsLongestPath, DAGLongestPath, ResourceEstimation

Utility passes (qiskit/transpiler/passes/utils/):
DAGFixedPoint, FixedPoint, ContainsInstruction

Specific changes

Add from __future__ import annotations to all 12 files
Type-annotate __init__ parameters (bool, str, set[str]) and
run() signatures (dag: DAGCircuit) with -> None return types
Expand sparse docstrings with Args blocks where missing
Fix incorrect module-level docstring in contains_instruction.py
(was a copy-paste leftover: "Check if a property reached a fixed point")
Rename the placeholder parameter _ to dag in
ResourceEstimation.run() for clarity and consistency

Motivation

These passes are part of the public API and used across the transpiler
pipeline, yet they lacked type annotations — hurting IDE auto-completion,
static analysis (mypy / pyright), and Sphinx-generated API documentation.
This is a low-risk, documentation-quality improvement with zero behavioral
changes.

How it was tested

ruff check — all checks passed
black --check — 13 files left unchanged
AST validation script — confirmed from __future__ import annotations
and typed run() return annotations present in all 12 files
Changes are purely additive type hints and docstrings; CI will validate
the full test suite

AI attribution

The preparation of this contribution was assisted by Claude Sonnet 4.6

Add `from __future__ import annotations` and PEP 484 type annotations to all 9 analysis passes (CountOps, Depth, Size, Width, NumQubits, NumTensorFactors, CountOpsLongestPath, DAGLongestPath, ResourceEstimation) and 3 utility passes (DAGFixedPoint, FixedPoint, ContainsInstruction). Changes include: - Type-annotate __init__ parameters and run() method signatures with DAGCircuit, bool, str, and -> None return types - Expand sparse docstrings with Args blocks where missing - Fix copy-paste module docstring in contains_instruction.py (was incorrectly 'Check if a property reached a fixed point') - Rename placeholder parameter '_' to 'dag' in ResourceEstimation.run() for clarity

qiskit-bot · 2026-03-18T22:22:51Z

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the following people are relevant to this code:

@Qiskit/terra-core

CLAassistant · 2026-03-18T22:22:52Z

All committers have signed the CLA.

CLAassistant · 2026-03-18T22:22:53Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

jakelishman · 2026-03-18T22:28:55Z

This is a pre-written response.

I believe this may have been LLM generated without attribution.

Please confirm the model used, and that the PR was tested and checked by a human before submission, including validating that the PR truly solves the issue at it was described, and takes into account any comments from maintainers in the base issues.

Hadar01 · 2026-03-19T08:54:41Z

@jakelishman

Thanks for flagging this. I used an AI assistant (Claude) to help generate the type hint changes. I want to be transparent about that.That said, I did review the generated output, understood the changes, and ran the relevant tests locally to verify nothing was broken:
python -m stestr run test.python.transpiler.test_count_ops_pass test.python.transpiler.test_fixed_point_pass test.python.transpiler.test_count_ops_longest_path_pass test.python.transpiler.test_resource_estimation_pass
Result: 12 passed, 0 failed, 0 skipped.
Also This was a proactive improvement, not tied to an open issue.
I believe the PR correctly adds PEP 484 type hints as described and doesn't break any existing functionality. Happy to make adjustments based on your review

Hadar01 · 2026-03-21T02:23:31Z

Hi @jakelishman ,I've addressed the transparency concern regarding AI assistance, ran all relevant tests locally (12 passed, 0 failed), and believe the changes are correct. Would appreciate your review when you get a chance. Happy to make any adjustments.

Cryoris · 2026-03-23T09:36:23Z

+        """Initialize a ``ContainsInstruction`` pass.



Our current suggestion is actually to just remove this initial sentence in __init__ if it doesn't provide any additional information

Suggested change

"""Initialize a ``ContainsInstruction`` pass.

"""

Agreed, removed

Cryoris · 2026-03-23T09:36:41Z


-    def __init__(self, instruction_name, recurse: bool = True):
-        """ContainsInstruction initializer.
+    def __init__(self, instruction_name: str | set[str], recurse: bool = True) -> None:


Why change from Iterable to set? That seems more restrictive

The original docstring already documented this as str | Iterable[str] so I've matched the type hint to that , changed back to str | Iterable[str] using collections.abc.Iterable.

Cryoris · 2026-03-23T09:38:15Z

-    def run(self, dag):
-        """Run the CountOps pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the CountOps pass on *dag*."""


*dag* is incorrect here, we use double quotes for code formatting (as you/Claude correctly did in other places):

``dag``

This applies to a bunch of other places too

Fixed,updated to dag across all affected files.

Cryoris · 2026-03-23T09:38:42Z


 """Count the operations in a DAG circuit."""

+from __future__ import annotations


These imports don't seem necessary in every file, could you only add them when required?

Replaced from __future__ import annotations with a TYPE_CHECKING guard instead ,this way DAGCircuit is only imported during static analysis and has zero runtime cost. Happy to remove it entirely if you'd prefer to keep the diff minimal.

Cryoris · 2026-03-23T09:39:45Z

    * Size()
    * CountOps()
    * NumTensorFactors()
+    * NumQubits()


Oh nice catch 👍🏻

Thanks! 😊

Co-authored-by: Julien Gacon <gaconju@gmail.com>

Hadar01

Thanks for the thorough review @Cryoris ! I've pushed a follow-up commit addressing all feedback:

1.Replaced from future import annotations with TYPE_CHECKING guard in all files
2.Fixed dag → dag across all files
3.Removed redundant init summary lines
4.Changed set[str] → str | Iterable[str] in contains_instruction.py
5.Removed the no-op docstring from resource_estimation.py

Please take another look when you get a chance!

Cryoris

Thanks for the updates, just one thing about line removals and then this LGTM

Cryoris · 2026-03-26T07:46:42Z

 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
-


IMO it's much easier to see the module docstring with this whitespace, could you leave these as they were?

Sorry about that! Restored the blank lines , will keep whitespace as in the originals going forward.

Cryoris · 2026-03-26T07:48:28Z

+        """Run the FixedPoint pass on ``dag``."""
        current_value = self.property_set[self._property]
        fixed_point_previous_property = f"_fixed_point_previous_{self._property}"
-


Maybe it'd be best to just revert all these line removals generally 😄

Sorry about that! Restored the blank lines ,will keep whitespace as in the originals going forward.

Hadar01

@Cryoris Done!

Add from __future__ import annotations to all 12 files so that type hints are treated as strings at runtime (fixing Python 3.10 NameError). Keep TYPE_CHECKING guard for DAGCircuit import to satisfy ruff F821. This matches the pattern used in basepasses.py and layout.py. Also fixes contains_instruction.py module docstring (was copy-paste from fixed_point.py).

Hadar01 · 2026-03-30T19:01:17Z

Hey @Cryoris , so I found out why CI was failing , using only the TYPE_CHECKING guard without from future import annotations breaks on Python 3.10 because the type hints get evaluated at runtime and DAGCircuit isn't actually imported. I've added back from future import annotations alongside the guard in all files. Looked at how basepasses.py and layout.py handle it and they use the same combo, so I followed that pattern. Also caught that contains_instruction.py still had the wrong module docstring from fixed_point.py, fixed that too. Let me know if this looks good!

Cryoris · 2026-04-24T13:54:19Z

Thanks for the updates, this looks good now. Could you update the PR description with the Claude model used (if you know it)?

Hadar01 · 2026-04-25T12:37:40Z

Thanks for the updates, this looks good now. Could you update the PR description with the Claude model used (if you know it)?

Done @Cryoris

coveralls · 2026-04-27T13:14:48Z

Coverage Report for CI Build 25011313525

Coverage increased (+0.006%) to 87.576%

Details

Coverage increased (+0.006%) from the base build.
Patch coverage: 43 of 43 lines across 12 files are fully covered (100%).
8 coverage regressions across 2 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

8 previously-covered lines in 2 files lost coverage.

File	Lines Losing Coverage	Coverage
crates/qasm2/src/lex.rs	6	92.03%
crates/circuit/src/parameter/symbol_expr.rs	2	74.17%

Coverage Stats


Relevant Lines:	119883
Covered Lines:	104989
Line Coverage:	87.58%
Coverage Strength:	982238.82 hits per line

💛 - Coveralls

Hadar01 requested a review from a team as a code owner March 18, 2026 22:22

qiskit-bot added the Community PR PRs from contributors that are not 'members' of the Qiskit repo label Mar 18, 2026

github-project-automation Bot added this to Contributor Monitoring Mar 18, 2026

Hadar01 added 2 commits March 19, 2026 18:20

Merge branch 'main' into feat/add-type-hints-analysis-passes

dd4df44

Merge branch 'main' into feat/add-type-hints-analysis-passes

8c5662d

Cryoris reviewed Mar 23, 2026

View reviewed changes

Hadar01 and others added 13 commits March 26, 2026 10:46

Refactor import statements in count_ops.py

f53935c

Refactor imports and update docstring formatting

57e984d

Refactor import statements and update docstring

2b6a512

Refactor imports and update docstring formatting

f953847

Refactor import statement for TYPE_CHECKING

5962863

Apply suggestion from @Cryoris

0d614bc

Co-authored-by: Julien Gacon <gaconju@gmail.com>

Refactor imports and docstring formatting

e9572cf

Refactor import statements and docstring formatting

9680725

Refactor imports and update docstring format

0bc1b34

Refactor import statements in width.py

74a9466

Update instruction_name type to Iterable in ContainsInstruction

66ee428

Update dag_fixed_point.py

3507ba7

Refactor imports and docstrings in fixed_point.py

ce141dd

Hadar01 commented Mar 26, 2026

View reviewed changes

Hadar01 requested a review from Cryoris March 26, 2026 07:07

Cryoris reviewed Mar 26, 2026

View reviewed changes

Add copyright notice and docstring to count_ops.py

5dd8d15

Hadar01 added 3 commits March 26, 2026 15:20

Fix fixed point property update logic

6a38dd8

Remove unnecessary blank line in fixed_point.py

573b959

Remove unnecessary blank line in dag_fixed_point.py

f18a82f

Hadar01 commented Mar 26, 2026

View reviewed changes

Hadar01 requested a review from Cryoris March 26, 2026 09:57

Hadar01 and others added 3 commits March 28, 2026 06:58

Merge branch 'main' into feat/add-type-hints-analysis-passes

ecc51c2

Merge branch 'main' into feat/add-type-hints-analysis-passes

7d5a06c

Cryoris approved these changes Apr 27, 2026

View reviewed changes

Cryoris enabled auto-merge April 27, 2026 12:49

Cryoris disabled auto-merge April 27, 2026 12:50

Cryoris enabled auto-merge April 27, 2026 13:35

Cryoris changed the title ~~docs: add PEP 484 type hints to transpiler analysis and utility passes~~ Add PEP 484 type hints to transpiler analysis and utility passes Apr 27, 2026

Cryoris added the Changelog: None Do not include in the GitHub Release changelog. label Apr 27, 2026

Cryoris added this pull request to the merge queue Apr 27, 2026

ShellyGarion added this to the 2.5.0 milestone Apr 27, 2026

github-project-automation Bot added this to Qiskit 2.5 Apr 27, 2026

github-project-automation Bot moved this to Ready in Qiskit 2.5 Apr 27, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Apr 27, 2026

Merge branch 'main' into feat/add-type-hints-analysis-passes

c8021f2

ShellyGarion enabled auto-merge April 28, 2026 05:48

ShellyGarion added this pull request to the merge queue Apr 28, 2026

Merged via the queue into Qiskit:main with commit b045984 Apr 28, 2026
45 of 47 checks passed

github-project-automation Bot moved this to Done in Contributor Monitoring Apr 28, 2026

github-project-automation Bot moved this from Ready to Done in Qiskit 2.5 Apr 28, 2026


		"""Count the operations in a DAG circuit."""

		from __future__ import annotations

Conversation

Hadar01 commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Specific changes

Motivation

How it was tested

AI attribution

Uh oh!

qiskit-bot commented Mar 18, 2026

Uh oh!

CLAassistant commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Mar 18, 2026

Uh oh!

jakelishman commented Mar 18, 2026

Uh oh!

Hadar01 commented Mar 19, 2026

Uh oh!

Hadar01 commented Mar 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hadar01 left a comment

Choose a reason for hiding this comment

Uh oh!

Cryoris left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hadar01 left a comment

Choose a reason for hiding this comment

Uh oh!

Hadar01 commented Mar 30, 2026

Uh oh!

Cryoris commented Apr 24, 2026

Uh oh!

Hadar01 commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 25011313525

Coverage increased (+0.006%) to 87.576%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

Uh oh!

Uh oh!

Reviewers

Hadar01 commented Mar 18, 2026 •

edited

Loading

CLAassistant commented Mar 18, 2026 •

edited

Loading

Hadar01 commented Apr 25, 2026 •

edited

Loading

coveralls commented Apr 27, 2026 •

edited

Loading